home *** CD-ROM | disk | FTP | other *** search
Text File | 1996-03-02 | 90.1 KB | 1,585 lines |
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- NNNNAAAAMMMMEEEE
- perlxs - XS language reference manual
-
- DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
- IIIInnnnttttrrrroooodddduuuuccccttttiiiioooonnnn
-
- XS is a language used to create an extension interface
- between Perl and some C library which one wishes to use
- with Perl. The XS interface is combined with the library
- to create a new library which can be linked to Perl. An
- XXXXSSSSUUUUBBBB is a function in the XS language and is the core
- component of the Perl application interface.
-
- The XS compiler is called xxxxssssuuuubbbbpppppppp. This compiler will
- embed the constructs necessary to let an XSUB, which is
- really a C function in disguise, manipulate Perl values
- and creates the glue necessary to let Perl access the
- XSUB. The compiler uses ttttyyyyppppeeeemmmmaaaappppssss to determine how to map
- C function parameters and variables to Perl values. The
- default typemap handles many common C types. A supplement
- typemap must be created to handle special structures and
- types for the library being linked.
-
- See the _p_e_r_l_x_s_t_u_t manpage for a tutorial on the whole
- extension creation process.
-
- OOOOnnnn TTTThhhheeee RRRRooooaaaadddd
-
- Many of the examples which follow will concentrate on
- creating an interface between Perl and the ONC+ RPC bind
- library functions. The _r_p_c_b___g_e_t_t_i_m_e_(_) function is used to
- demonstrate many features of the XS language. This
- function has two parameters; the first is an input
- parameter and the second is an output parameter. The
- function also returns a status value.
-
- bbbboooooooollll____tttt rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****hhhhoooosssstttt,,,, ttttiiiimmmmeeee____tttt ****ttttiiiimmmmeeeepppp))));;;;
-
- From C this function will be called with the following
- statements.
-
- ####iiiinnnncccclllluuuuddddeeee <<<<rrrrppppcccc////rrrrppppcccc....hhhh>>>>
- bbbboooooooollll____tttt ssssttttaaaattttuuuussss;;;;
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp;;;;
- ssssttttaaaattttuuuussss ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( """"llllooooccccaaaallllhhhhoooosssstttt"""",,,, &&&&ttttiiiimmmmeeeepppp ))));;;;
-
- If an XSUB is created to offer a direct translation
- between this function and Perl, then this XSUB will be
- used from Perl with the following code. The $$$$ssssttttaaaattttuuuussss and
- $$$$ttttiiiimmmmeeeepppp variables will contain the output of the function.
-
- uuuusssseeee RRRRPPPPCCCC;;;;
- $$$$ssssttttaaaattttuuuussss ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( """"llllooooccccaaaallllhhhhoooosssstttt"""",,,, $$$$ttttiiiimmmmeeeepppp ))));;;;
-
-
-
-
- 15/Feb/96 perl 5.002 with 1
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- The following XS file shows an XS subroutine, or XSUB,
- which demonstrates one possible interface to the
- _r_p_c_b___g_e_t_t_i_m_e_(_) function. This XSUB represents a direct
- translation between C and Perl and so preserves the
- interface even from Perl. This XSUB will be invoked from
- Perl with the usage shown above. Note that the first
- three #include statements, for EEEEXXXXTTTTEEEERRRRNNNN....hhhh, ppppeeeerrrrllll....hhhh, and
- XXXXSSSSUUUUBBBB....hhhh, will always be present at the beginning of an XS
- file. This approach and others will be expanded later in
- this document.
-
- ####iiiinnnncccclllluuuuddddeeee """"EEEEXXXXTTTTEEEERRRRNNNN....hhhh""""
- ####iiiinnnncccclllluuuuddddeeee """"ppppeeeerrrrllll....hhhh""""
- ####iiiinnnncccclllluuuuddddeeee """"XXXXSSSSUUUUBBBB....hhhh""""
- ####iiiinnnncccclllluuuuddddeeee <<<<rrrrppppcccc////rrrrppppcccc....hhhh>>>>
-
- MMMMOOOODDDDUUUULLLLEEEE ==== RRRRPPPPCCCC PPPPAAAACCCCKKKKAAAAGGGGEEEE ==== RRRRPPPPCCCC
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- ttttiiiimmmmeeee____tttt &&&&ttttiiiimmmmeeeepppp
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
-
- Any extension to Perl, including those containing XSUBs,
- should have a Perl module to serve as the bootstrap which
- pulls the extension into Perl. This module will export
- the extension's functions and variables to the Perl
- program and will cause the extension's XSUBs to be linked
- into Perl. The following module will be used for most of
- the examples in this document and should be used from Perl
- with the uuuusssseeee command as shown earlier. Perl modules are
- explained in more detail later in this document.
-
- ppppaaaacccckkkkaaaaggggeeee RRRRPPPPCCCC;;;;
-
- rrrreeeeqqqquuuuiiiirrrreeee EEEExxxxppppoooorrrrtttteeeerrrr;;;;
- rrrreeeeqqqquuuuiiiirrrreeee DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr;;;;
- @@@@IIIISSSSAAAA ==== qqqqwwww((((EEEExxxxppppoooorrrrtttteeeerrrr DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr))));;;;
- @@@@EEEEXXXXPPPPOOOORRRRTTTT ==== qqqqwwww(((( rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee ))));;;;
-
- bbbboooooooottttssssttttrrrraaaapppp RRRRPPPPCCCC;;;;
- 1111;;;;
-
- Throughout this document a variety of interfaces to the
- _r_p_c_b___g_e_t_t_i_m_e_(_) XSUB will be explored. The XSUBs will take
- their parameters in different orders or will take
- different numbers of parameters. In each case the XSUB is
- an abstraction between Perl and the real C _r_p_c_b___g_e_t_t_i_m_e_(_)
- function, and the XSUB must always ensure that the real
- _r_p_c_b___g_e_t_t_i_m_e_(_) function is called with the correct
- parameters. This abstraction will allow the programmer to
- create a more Perl-like interface to the C function.
-
-
-
- 15/Feb/96 perl 5.002 with 2
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- TTTThhhheeee AAAAnnnnaaaattttoooommmmyyyy ooooffff aaaannnn XXXXSSSSUUUUBBBB
-
- The following XSUB allows a Perl program to access a C
- library function called _s_i_n_(_). The XSUB will imitate the
- C function which takes a single argument and returns a
- single value.
-
- ddddoooouuuubbbblllleeee
- ssssiiiinnnn((((xxxx))))
- ddddoooouuuubbbblllleeee xxxx
-
- When using C pointers the indirection operator **** should be
- considered part of the type and the address operator &&&&
- should be considered part of the variable, as is
- demonstrated in the _r_p_c_b___g_e_t_t_i_m_e_(_) function above. See
- the section on typemaps for more about handling qualifiers
- and unary operators in C types.
-
- The function name and the return type must be placed on
- separate lines.
-
- IIIINNNNCCCCOOOORRRRRRRREEEECCCCTTTT CCCCOOOORRRRRRRREEEECCCCTTTT
-
- ddddoooouuuubbbblllleeee ssssiiiinnnn((((xxxx)))) ddddoooouuuubbbblllleeee
- ddddoooouuuubbbblllleeee xxxx ssssiiiinnnn((((xxxx))))
- ddddoooouuuubbbblllleeee xxxx
-
- The function body may be indented or left-adjusted. The
- following example shows a function with its body left-
- adjusted. Most examples in this document will indent the
- body.
-
- CCCCOOOORRRRRRRREEEECCCCTTTT
-
- ddddoooouuuubbbblllleeee
- ssssiiiinnnn((((xxxx))))
- ddddoooouuuubbbblllleeee xxxx
-
-
- TTTThhhheeee AAAArrrrgggguuuummmmeeeennnntttt SSSSttttaaaacccckkkk
-
- The argument stack is used to store the values which are
- sent as parameters to the XSUB and to store the XSUB's
- return value. In reality all Perl functions keep their
- values on this stack at the same time, each limited to its
- own range of positions on the stack. In this document the
- first position on that stack which belongs to the active
- function will be referred to as position 0 for that
- function.
-
- XSUBs refer to their stack arguments with the macro SSSSTTTT((((xxxx)))),
- where _x refers to a position in this XSUB's part of the
- stack. Position 0 for that function would be known to the
- XSUB as _S_T(0). The XSUB's incoming parameters and
-
-
-
- 15/Feb/96 perl 5.002 with 3
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- outgoing return values always begin at _S_T(0). For many
- simple cases the xxxxssssuuuubbbbpppppppp compiler will generate the code
- necessary to handle the argument stack by embedding code
- fragments found in the typemaps. In more complex cases
- the programmer must supply the code.
-
- TTTThhhheeee RRRREEEETTTTVVVVAAAALLLL VVVVaaaarrrriiiiaaaabbbblllleeee
-
- The RETVAL variable is a magic variable which always
- matches the return type of the C library function. The
- xxxxssssuuuubbbbpppppppp compiler will supply this variable in each XSUB and
- by default will use it to hold the return value of the C
- library function being called. In simple cases the value
- of RETVAL will be placed in _S_T(0) of the argument stack
- where it can be received by Perl as the return value of
- the XSUB.
-
- If the XSUB has a return type of vvvvooooiiiidddd then the compiler
- will not supply a RETVAL variable for that function. When
- using the PPCODE: directive the RETVAL variable may not be
- needed.
-
- TTTThhhheeee MMMMOOOODDDDUUUULLLLEEEE KKKKeeeeyyyywwwwoooorrrrdddd
-
- The MODULE keyword is used to start the XS code and to
- specify the package of the functions which are being
- defined. All text preceding the first MODULE keyword is
- considered C code and is passed through to the output
- untouched. Every XS module will have a bootstrap function
- which is used to hook the XSUBs into Perl. The package
- name of this bootstrap function will match the value of
- the last MODULE statement in the XS source files. The
- value of MODULE should always remain constant within the
- same XS file, though this is not required.
-
- The following example will start the XS code and will
- place all functions in a package named RPC.
-
- MMMMOOOODDDDUUUULLLLEEEE ==== RRRRPPPPCCCC
-
-
- TTTThhhheeee PPPPAAAACCCCKKKKAAAAGGGGEEEE KKKKeeeeyyyywwwwoooorrrrdddd
-
- When functions within an XS source file must be separated
- into packages the PACKAGE keyword should be used. This
- keyword is used with the MODULE keyword and must follow
- immediately after it when used.
-
- MMMMOOOODDDDUUUULLLLEEEE ==== RRRRPPPPCCCC PPPPAAAACCCCKKKKAAAAGGGGEEEE ==== RRRRPPPPCCCC
-
- [[[[ XXXXSSSS ccccooooddddeeee iiiinnnn ppppaaaacccckkkkaaaaggggeeee RRRRPPPPCCCC ]]]]
-
- MMMMOOOODDDDUUUULLLLEEEE ==== RRRRPPPPCCCC PPPPAAAACCCCKKKKAAAAGGGGEEEE ==== RRRRPPPPCCCCBBBB
-
-
-
-
- 15/Feb/96 perl 5.002 with 4
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- [[[[ XXXXSSSS ccccooooddddeeee iiiinnnn ppppaaaacccckkkkaaaaggggeeee RRRRPPPPCCCCBBBB ]]]]
-
- MMMMOOOODDDDUUUULLLLEEEE ==== RRRRPPPPCCCC PPPPAAAACCCCKKKKAAAAGGGGEEEE ==== RRRRPPPPCCCC
-
- [[[[ XXXXSSSS ccccooooddddeeee iiiinnnn ppppaaaacccckkkkaaaaggggeeee RRRRPPPPCCCC ]]]]
-
- Although this keyword is optional and in some cases
- provides redundant information it should always be used.
- This keyword will ensure that the XSUBs appear in the
- desired package.
-
- TTTThhhheeee PPPPRRRREEEEFFFFIIIIXXXX KKKKeeeeyyyywwwwoooorrrrdddd
-
- The PREFIX keyword designates prefixes which should be
- removed from the Perl function names. If the C function
- is rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((()))) and the PREFIX value is rrrrppppccccbbbb____ then Perl
- will see this function as ggggeeeettttttttiiiimmmmeeee(((()))).
-
- This keyword should follow the PACKAGE keyword when used.
- If PACKAGE is not used then PREFIX should follow the
- MODULE keyword.
-
- MMMMOOOODDDDUUUULLLLEEEE ==== RRRRPPPPCCCC PPPPRRRREEEEFFFFIIIIXXXX ==== rrrrppppcccc____
-
- MMMMOOOODDDDUUUULLLLEEEE ==== RRRRPPPPCCCC PPPPAAAACCCCKKKKAAAAGGGGEEEE ==== RRRRPPPPCCCCBBBB PPPPRRRREEEEFFFFIIIIXXXX ==== rrrrppppccccbbbb____
-
-
- TTTThhhheeee OOOOUUUUTTTTPPPPUUUUTTTT:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- The OUTPUT: keyword indicates that certain function
- parameters should be updated (new values made visible to
- Perl) when the XSUB terminates or that certain values
- should be returned to the calling Perl function. For
- simple functions, such as the _s_i_n_(_) function above, the
- RETVAL variable is automatically designated as an output
- value. In more complex functions the xxxxssssuuuubbbbpppppppp compiler will
- need help to determine which variables are output
- variables.
-
- This keyword will normally be used to complement the CODE:
- keyword. The RETVAL variable is not recognized as an
- output variable when the CODE: keyword is present. The
- OUTPUT: keyword is used in this situation to tell the
- compiler that RETVAL really is an output variable.
-
- The OUTPUT: keyword can also be used to indicate that
- function parameters are output variables. This may be
- necessary when a parameter has been modified within the
- function and the programmer would like the update to be
- seen by Perl.
-
-
-
-
-
-
-
- 15/Feb/96 perl 5.002 with 5
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- ttttiiiimmmmeeee____tttt &&&&ttttiiiimmmmeeeepppp
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
-
- The OUTPUT: keyword will also allow an output parameter to
- be mapped to a matching piece of code rather than to a
- typemap.
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- ttttiiiimmmmeeee____tttt &&&&ttttiiiimmmmeeeepppp
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp ssssvvvv____sssseeeettttnnnnvvvv((((SSSSTTTT((((1111)))),,,, ((((ddddoooouuuubbbblllleeee))))ttttiiiimmmmeeeepppp))));;;;
-
-
- TTTThhhheeee CCCCOOOODDDDEEEE:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- This keyword is used in more complicated XSUBs which
- require special handling for the C function. The RETVAL
- variable is available but will not be returned unless it
- is specified under the OUTPUT: keyword.
-
- The following XSUB is for a C function which requires
- special handling of its parameters. The Perl usage is
- given first.
-
- $$$$ssssttttaaaattttuuuussss ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( """"llllooooccccaaaallllhhhhoooosssstttt"""",,,, $$$$ttttiiiimmmmeeeepppp ))));;;;
-
- The XSUB follows.
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp
- CCCCOOOODDDDEEEE::::
- RRRREEEETTTTVVVVAAAALLLL ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhhoooosssstttt,,,, &&&&ttttiiiimmmmeeeepppp ))));;;;
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
- RRRREEEETTTTVVVVAAAALLLL
-
-
- TTTThhhheeee IIIINNNNIIIITTTT:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- The INIT: keyword allows initialization to be inserted
- into the XSUB before the compiler generates the call to
- the C function. Unlike the CODE: keyword above, this
- keyword does not affect the way the compiler handles
- RETVAL.
-
-
-
-
-
- 15/Feb/96 perl 5.002 with 6
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- ttttiiiimmmmeeee____tttt &&&&ttttiiiimmmmeeeepppp
- IIIINNNNIIIITTTT::::
- pppprrrriiiinnnnttttffff((((""""#### HHHHoooosssstttt iiiissss %%%%ssss\\\\nnnn"""",,,, hhhhoooosssstttt ))));;;;
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
-
-
- TTTThhhheeee NNNNOOOO____IIIINNNNIIIITTTT KKKKeeeeyyyywwwwoooorrrrdddd
-
- The NO_INIT keyword is used to indicate that a function
- parameter is being used as only an output value. The
- xxxxssssuuuubbbbpppppppp compiler will normally generate code to read the
- values of all function parameters from the argument stack
- and assign them to C variables upon entry to the function.
- NO_INIT will tell the compiler that some parameters will
- be used for output rather than for input and that they
- will be handled before the function terminates.
-
- The following example shows a variation of the
- _r_p_c_b___g_e_t_t_i_m_e_(_) function. This function uses the timep
- variable as only an output variable and does not care
- about its initial contents.
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- ttttiiiimmmmeeee____tttt &&&&ttttiiiimmmmeeeepppp ==== NNNNOOOO____IIIINNNNIIIITTTT
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
-
-
- IIIInnnniiiittttiiiiaaaalllliiiizzzziiiinnnngggg FFFFuuuunnnnccccttttiiiioooonnnn PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss
-
- Function parameters are normally initialized with their
- values from the argument stack. The typemaps contain the
- code segments which are used to transfer the Perl values
- to the C parameters. The programmer, however, is allowed
- to override the typemaps and supply alternate
- initialization code.
-
- The following code demonstrates how to supply
- initialization code for function parameters. The
- initialization code is eval'd by the compiler before it is
- added to the output so anything which should be
- interpreted literally, such as double quotes, must be
- protected with backslashes.
-
-
-
-
-
-
-
-
- 15/Feb/96 perl 5.002 with 7
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt ==== ((((cccchhhhaaaarrrr ****))))SSSSvvvvPPPPVVVV((((SSSSTTTT((((0000)))),,,,nnnnaaaa))));;;;
- ttttiiiimmmmeeee____tttt &&&&ttttiiiimmmmeeeepppp ==== 0000;;;;
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
-
- This should not be used to supply default values for
- parameters. One would normally use this when a function
- parameter must be processed by another library function
- before it can be used. Default parameters are covered in
- the next section.
-
- DDDDeeeeffffaaaauuuulllltttt PPPPaaaarrrraaaammmmeeeetttteeeerrrr VVVVaaaalllluuuueeeessss
-
- Default values can be specified for function parameters by
- placing an assignment statement in the parameter list.
- The default value may be a number or a string. Defaults
- should always be used on the right-most parameters only.
-
- To allow the XSUB for _r_p_c_b___g_e_t_t_i_m_e_(_) to have a default
- host value the parameters to the XSUB could be rearranged.
- The XSUB will then call the real _r_p_c_b___g_e_t_t_i_m_e_(_) function
- with the parameters in the correct order. Perl will call
- this XSUB with either of the following statements.
-
- $$$$ssssttttaaaattttuuuussss ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( $$$$ttttiiiimmmmeeeepppp,,,, $$$$hhhhoooosssstttt ))));;;;
-
- $$$$ssssttttaaaattttuuuussss ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( $$$$ttttiiiimmmmeeeepppp ))));;;;
-
- The XSUB will look like the code which follows. A
- CODE: block is used to call the real _r_p_c_b___g_e_t_t_i_m_e_(_)
- function with the parameters in the correct order for that
- function.
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((ttttiiiimmmmeeeepppp,,,,hhhhoooosssstttt====""""llllooooccccaaaallllhhhhoooosssstttt""""))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp ==== NNNNOOOO____IIIINNNNIIIITTTT
- CCCCOOOODDDDEEEE::::
- RRRREEEETTTTVVVVAAAALLLL ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhhoooosssstttt,,,, &&&&ttttiiiimmmmeeeepppp ))));;;;
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
- RRRREEEETTTTVVVVAAAALLLL
-
-
- TTTThhhheeee PPPPRRRREEEEIIIINNNNIIIITTTT:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- The PREINIT: keyword allows extra variables to be declared
- before the typemaps are expanded. If a variable is
- declared in a CODE: block then that variable will follow
- any typemap code. This may result in a C syntax error.
- To force the variable to be declared before the typemap
- code, place it into a PREINIT: block. The PREINIT:
-
-
-
- 15/Feb/96 perl 5.002 with 8
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- keyword may be used one or more times within an XSUB.
-
- The following examples are equivalent, but if the code is
- using complex typemaps then the first example is safer.
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((ttttiiiimmmmeeeepppp))))
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp ==== NNNNOOOO____IIIINNNNIIIITTTT
- PPPPRRRREEEEIIIINNNNIIIITTTT::::
- cccchhhhaaaarrrr ****hhhhoooosssstttt ==== """"llllooooccccaaaallllhhhhoooosssstttt"""";;;;
- CCCCOOOODDDDEEEE::::
- RRRREEEETTTTVVVVAAAALLLL ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhhoooosssstttt,,,, &&&&ttttiiiimmmmeeeepppp ))));;;;
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
- RRRREEEETTTTVVVVAAAALLLL
-
- A correct, but error-prone example.
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((ttttiiiimmmmeeeepppp))))
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp ==== NNNNOOOO____IIIINNNNIIIITTTT
- CCCCOOOODDDDEEEE::::
- cccchhhhaaaarrrr ****hhhhoooosssstttt ==== """"llllooooccccaaaallllhhhhoooosssstttt"""";;;;
- RRRREEEETTTTVVVVAAAALLLL ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhhoooosssstttt,,,, &&&&ttttiiiimmmmeeeepppp ))));;;;
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
- RRRREEEETTTTVVVVAAAALLLL
-
-
- TTTThhhheeee IIIINNNNPPPPUUUUTTTT:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- The XSUB's parameters are usually evaluated immediately
- after entering the XSUB. The INPUT: keyword can be used
- to force those parameters to be evaluated a little later.
- The INPUT: keyword can be used multiple times within an
- XSUB and can be used to list one or more input variables.
- This keyword is used with the PREINIT: keyword.
-
- The following example shows how the input parameter ttttiiiimmmmeeeepppp
- can be evaluated late, after a PREINIT.
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- PPPPRRRREEEEIIIINNNNIIIITTTT::::
- ttttiiiimmmmeeee____tttt tttttttt;;;;
- IIIINNNNPPPPUUUUTTTT::::
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp
- CCCCOOOODDDDEEEE::::
- RRRREEEETTTTVVVVAAAALLLL ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhhoooosssstttt,,,, &&&&tttttttt ))));;;;
- ttttiiiimmmmeeeepppp ==== tttttttt;;;;
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
- RRRREEEETTTTVVVVAAAALLLL
-
-
-
- 15/Feb/96 perl 5.002 with 9
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- The next example shows each input parameter evaluated
- late.
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- PPPPRRRREEEEIIIINNNNIIIITTTT::::
- ttttiiiimmmmeeee____tttt tttttttt;;;;
- IIIINNNNPPPPUUUUTTTT::::
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- PPPPRRRREEEEIIIINNNNIIIITTTT::::
- cccchhhhaaaarrrr ****hhhh;;;;
- IIIINNNNPPPPUUUUTTTT::::
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp
- CCCCOOOODDDDEEEE::::
- hhhh ==== hhhhoooosssstttt;;;;
- RRRREEEETTTTVVVVAAAALLLL ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhh,,,, &&&&tttttttt ))));;;;
- ttttiiiimmmmeeeepppp ==== tttttttt;;;;
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
- RRRREEEETTTTVVVVAAAALLLL
-
-
- VVVVaaaarrrriiiiaaaabbbblllleeee----lllleeeennnnggggtttthhhh PPPPaaaarrrraaaammmmeeeetttteeeerrrr LLLLiiiissssttttssss
-
- XSUBs can have variable-length parameter lists by
- specifying an ellipsis ((((............)))) in the parameter list. This
- use of the ellipsis is similar to that found in ANSI C.
- The programmer is able to determine the number of
- arguments passed to the XSUB by examining the iiiitttteeeemmmmssss
- variable which the xxxxssssuuuubbbbpppppppp compiler supplies for all XSUBs.
- By using this mechanism one can create an XSUB which
- accepts a list of parameters of unknown length.
-
- The _h_o_s_t parameter for the _r_p_c_b___g_e_t_t_i_m_e_(_) XSUB can be
- optional so the ellipsis can be used to indicate that the
- XSUB will take a variable number of parameters. Perl
- should be able to call this XSUB with either of the
- following statements.
-
- $$$$ssssttttaaaattttuuuussss ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( $$$$ttttiiiimmmmeeeepppp,,,, $$$$hhhhoooosssstttt ))));;;;
-
- $$$$ssssttttaaaattttuuuussss ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( $$$$ttttiiiimmmmeeeepppp ))));;;;
-
- The XS code, with ellipsis, follows.
-
-
-
-
-
-
-
-
-
-
-
-
-
- 15/Feb/96 perl 5.002 with 10
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((ttttiiiimmmmeeeepppp,,,, ............))))
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp ==== NNNNOOOO____IIIINNNNIIIITTTT
- PPPPRRRREEEEIIIINNNNIIIITTTT::::
- cccchhhhaaaarrrr ****hhhhoooosssstttt ==== """"llllooooccccaaaallllhhhhoooosssstttt"""";;;;
- CCCCOOOODDDDEEEE::::
- iiiiffff(((( iiiitttteeeemmmmssss >>>> 1111 ))))
- hhhhoooosssstttt ==== ((((cccchhhhaaaarrrr ****))))SSSSvvvvPPPPVVVV((((SSSSTTTT((((1111)))),,,, nnnnaaaa))));;;;
- RRRREEEETTTTVVVVAAAALLLL ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhhoooosssstttt,,,, &&&&ttttiiiimmmmeeeepppp ))));;;;
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
- RRRREEEETTTTVVVVAAAALLLL
-
-
- TTTThhhheeee PPPPPPPPCCCCOOOODDDDEEEE:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- The PPCODE: keyword is an alternate form of the CODE:
- keyword and is used to tell the xxxxssssuuuubbbbpppppppp compiler that the
- programmer is supplying the code to control the argument
- stack for the XSUBs return values. Occasionally one will
- want an XSUB to return a list of values rather than a
- single value. In these cases one must use PPCODE: and
- then explicitly push the list of values on the stack. The
- PPCODE: and CODE: keywords are not used together within
- the same XSUB.
-
- The following XSUB will call the C _r_p_c_b___g_e_t_t_i_m_e_(_) function
- and will return its two output values, timep and status,
- to Perl as a single list.
-
- vvvvooooiiiidddd
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- PPPPRRRREEEEIIIINNNNIIIITTTT::::
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp;;;;
- bbbboooooooollll____tttt ssssttttaaaattttuuuussss;;;;
- PPPPPPPPCCCCOOOODDDDEEEE::::
- ssssttttaaaattttuuuussss ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhhoooosssstttt,,,, &&&&ttttiiiimmmmeeeepppp ))));;;;
- EEEEXXXXTTTTEEEENNNNDDDD((((sssspppp,,,, 2222))));;;;
- PPPPUUUUSSSSHHHHssss((((ssssvvvv____2222mmmmoooorrrrttttaaaallll((((nnnneeeewwwwSSSSVVVViiiivvvv((((ssssttttaaaattttuuuussss))))))))))));;;;
- PPPPUUUUSSSSHHHHssss((((ssssvvvv____2222mmmmoooorrrrttttaaaallll((((nnnneeeewwwwSSSSVVVViiiivvvv((((ttttiiiimmmmeeeepppp))))))))))));;;;
-
- Notice that the programmer must supply the C code
- necessary to have the real _r_p_c_b___g_e_t_t_i_m_e_(_) function called
- and to have the return values properly placed on the
- argument stack.
-
- The vvvvooooiiiidddd return type for this function tells the xxxxssssuuuubbbbpppppppp
- compiler that the RETVAL variable is not needed or used
- and that it should not be created. In most scenarios the
- void return type should be used with the PPCODE:
- directive.
-
- The _E_X_T_E_N_D_(_) macro is used to make room on the argument
-
-
-
- 15/Feb/96 perl 5.002 with 11
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- stack for 2 return values. The PPCODE: directive causes
- the xxxxssssuuuubbbbpppppppp compiler to create a stack pointer called sssspppp,
- and it is this pointer which is being used in the _E_X_T_E_N_D_(_)
- macro. The values are then pushed onto the stack with the
- _P_U_S_H_s_(_) macro.
-
- Now the _r_p_c_b___g_e_t_t_i_m_e_(_) function can be used from Perl with
- the following statement.
-
- (((($$$$ssssttttaaaattttuuuussss,,,, $$$$ttttiiiimmmmeeeepppp)))) ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((""""llllooooccccaaaallllhhhhoooosssstttt""""))));;;;
-
-
- RRRReeeettttuuuurrrrnnnniiiinnnngggg UUUUnnnnddddeeeeffff AAAAnnnndddd EEEEmmmmppppttttyyyy LLLLiiiissssttttssss
-
- Occasionally the programmer will want to simply return
- uuuunnnnddddeeeeffff or an empty list if a function fails rather than a
- separate status value. The _r_p_c_b___g_e_t_t_i_m_e_(_) function offers
- just this situation. If the function succeeds we would
- like to have it return the time and if it fails we would
- like to have undef returned. In the following Perl code
- the value of $$$$ttttiiiimmmmeeeepppp will either be undef or it will be a
- valid time.
-
- $$$$ttttiiiimmmmeeeepppp ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( """"llllooooccccaaaallllhhhhoooosssstttt"""" ))));;;;
-
- The following XSUB uses the vvvvooooiiiidddd return type to disable
- the generation of the RETVAL variable and uses a CODE:
- block to indicate to the compiler that the programmer has
- supplied all the necessary code. The _s_v___n_e_w_m_o_r_t_a_l_(_) call
- will initialize the return value to undef, making that the
- default return value.
-
- vvvvooooiiiidddd
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt))))
- cccchhhhaaaarrrr **** hhhhoooosssstttt
- PPPPRRRREEEEIIIINNNNIIIITTTT::::
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp;;;;
- bbbboooooooollll____tttt xxxx;;;;
- CCCCOOOODDDDEEEE::::
- SSSSTTTT((((0000)))) ==== ssssvvvv____nnnneeeewwwwmmmmoooorrrrttttaaaallll(((())));;;;
- iiiiffff(((( rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhhoooosssstttt,,,, &&&&ttttiiiimmmmeeeepppp )))) ))))
- ssssvvvv____sssseeeettttnnnnvvvv(((( SSSSTTTT((((0000)))),,,, ((((ddddoooouuuubbbblllleeee))))ttttiiiimmmmeeeepppp))));;;;
-
- The next example demonstrates how one would place an
- explicit undef in the return value, should the need arise.
-
-
-
-
-
-
-
-
-
-
-
-
- 15/Feb/96 perl 5.002 with 12
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- vvvvooooiiiidddd
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt))))
- cccchhhhaaaarrrr **** hhhhoooosssstttt
- PPPPRRRREEEEIIIINNNNIIIITTTT::::
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp;;;;
- bbbboooooooollll____tttt xxxx;;;;
- CCCCOOOODDDDEEEE::::
- SSSSTTTT((((0000)))) ==== ssssvvvv____nnnneeeewwwwmmmmoooorrrrttttaaaallll(((())));;;;
- iiiiffff(((( rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhhoooosssstttt,,,, &&&&ttttiiiimmmmeeeepppp )))) )))){{{{
- ssssvvvv____sssseeeettttnnnnvvvv(((( SSSSTTTT((((0000)))),,,, ((((ddddoooouuuubbbblllleeee))))ttttiiiimmmmeeeepppp))));;;;
- }}}}
- eeeellllsssseeee{{{{
- SSSSTTTT((((0000)))) ==== &&&&ssssvvvv____uuuunnnnddddeeeeffff;;;;
- }}}}
-
- To return an empty list one must use a PPCODE: block and
- then not push return values on the stack.
-
- vvvvooooiiiidddd
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- PPPPRRRREEEEIIIINNNNIIIITTTT::::
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp;;;;
- PPPPPPPPCCCCOOOODDDDEEEE::::
- iiiiffff(((( rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhhoooosssstttt,,,, &&&&ttttiiiimmmmeeeepppp )))) ))))
- PPPPUUUUSSSSHHHHssss((((ssssvvvv____2222mmmmoooorrrrttttaaaallll((((nnnneeeewwwwSSSSVVVViiiivvvv((((ttttiiiimmmmeeeepppp))))))))))));;;;
- eeeellllsssseeee{{{{
- ////**** NNNNooootttthhhhiiiinnnngggg ppppuuuusssshhhheeeedddd oooonnnn ssssttttaaaacccckkkk,,,, ssssoooo aaaannnn eeeemmmmppppttttyyyy ****////
- ////**** lllliiiisssstttt iiiissss iiiimmmmpppplllliiiicccciiiittttllllyyyy rrrreeeettttuuuurrrrnnnneeeedddd.... ****////
- }}}}
-
-
- TTTThhhheeee RRRREEEEQQQQUUUUIIIIRRRREEEE:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- The REQUIRE: keyword is used to indicate the minimum
- version of the xxxxssssuuuubbbbpppppppp compiler needed to compile the XS
- module. An XS module which contains the following
- statement will only compile with xxxxssssuuuubbbbpppppppp version 1.922 or
- greater:
-
- RRRREEEEQQQQUUUUIIIIRRRREEEE:::: 1111....999922222222
-
-
- TTTThhhheeee CCCCLLLLEEEEAAAANNNNUUUUPPPP:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- This keyword can be used when an XSUB requires special
- cleanup procedures before it terminates. When the
- CLEANUP: keyword is used it must follow any CODE:,
- PPCODE:, or OUTPUT: blocks which are present in the XSUB.
- The code specified for the cleanup block will be added as
- the last statements in the XSUB.
-
-
-
-
-
-
- 15/Feb/96 perl 5.002 with 13
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- TTTThhhheeee BBBBOOOOOOOOTTTT:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- The BOOT: keyword is used to add code to the extension's
- bootstrap function. The bootstrap function is generated
- by the xxxxssssuuuubbbbpppppppp compiler and normally holds the statements
- necessary to register any XSUBs with Perl. With the BOOT:
- keyword the programmer can tell the compiler to add extra
- statements to the bootstrap function.
-
- This keyword may be used any time after the first MODULE
- keyword and should appear on a line by itself. The first
- blank line after the keyword will terminate the code
- block.
-
- BBBBOOOOOOOOTTTT::::
- #### TTTThhhheeee ffffoooolllllllloooowwwwiiiinnnngggg mmmmeeeessssssssaaaaggggeeee wwwwiiiillllllll bbbbeeee pppprrrriiiinnnntttteeeedddd wwwwhhhheeeennnn tttthhhheeee
- #### bbbboooooooottttssssttttrrrraaaapppp ffffuuuunnnnccccttttiiiioooonnnn eeeexxxxeeeeccccuuuutttteeeessss....
- pppprrrriiiinnnnttttffff((((""""HHHHeeeelllllllloooo ffffrrrroooommmm tttthhhheeee bbbboooooooottttssssttttrrrraaaapppp!!!!\\\\nnnn""""))));;;;
-
-
- TTTThhhheeee VVVVEEEERRRRSSSSIIIIOOOONNNNCCCCHHHHEEEECCCCKKKK:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- The VERSIONCHECK: keyword corresponds to xxxxssssuuuubbbbpppppppp's
- ----vvvveeeerrrrssssiiiioooonnnncccchhhheeeecccckkkk and ----nnnnoooovvvveeeerrrrssssiiiioooonnnncccchhhheeeecccckkkk options. This keyword
- overrides the commandline options. Version checking is
- enabled by default. When version checking is enabled the
- XS module will attempt to verify that its version matches
- the version of the PM module.
-
- To enable version checking:
-
- VVVVEEEERRRRSSSSIIIIOOOONNNNCCCCHHHHEEEECCCCKKKK:::: EEEENNNNAAAABBBBLLLLEEEE
-
- To disable version checking:
-
- VVVVEEEERRRRSSSSIIIIOOOONNNNCCCCHHHHEEEECCCCKKKK:::: DDDDIIIISSSSAAAABBBBLLLLEEEE
-
-
- TTTThhhheeee PPPPRRRROOOOTTTTOOOOTTTTYYYYPPPPEEEESSSS:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- The PROTOTYPES: keyword corresponds to xxxxssssuuuubbbbpppppppp's
- ----pppprrrroooottttoooottttyyyyppppeeeessss and ----nnnnoooopppprrrroooottttoooottttyyyyppppeeeessss options. This keyword
- overrides the commandline options. Prototypes are enabled
- by default. When prototypes are enabled XSUBs will be
- given Perl prototypes. This keyword may be used multiple
- times in an XS module to enable and disable prototypes for
- different parts of the module.
-
- To enable prototypes:
-
- PPPPRRRROOOOTTTTOOOOTTTTYYYYPPPPEEEESSSS:::: EEEENNNNAAAABBBBLLLLEEEE
-
- To disable prototypes:
-
-
-
-
- 15/Feb/96 perl 5.002 with 14
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- PPPPRRRROOOOTTTTOOOOTTTTYYYYPPPPEEEESSSS:::: DDDDIIIISSSSAAAABBBBLLLLEEEE
-
-
- TTTThhhheeee PPPPRRRROOOOTTTTOOOOTTTTYYYYPPPPEEEE:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- This keyword is similar to the PROTOTYPES: keyword above
- but can be used to force xxxxssssuuuubbbbpppppppp to use a specific
- prototype for the XSUB. This keyword overrides all other
- prototype options and keywords but affects only the
- current XSUB. Consult the PPPPrrrroooottttoooottttyyyyppppeeeessss entry in the _p_e_r_l_s_u_b
- manpage for information about Perl prototypes.
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((ttttiiiimmmmeeeepppp,,,, ............))))
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp ==== NNNNOOOO____IIIINNNNIIIITTTT
- PPPPRRRROOOOTTTTOOOOTTTTYYYYPPPPEEEE:::: $$$$;;;;$$$$
- PPPPRRRREEEEIIIINNNNIIIITTTT::::
- cccchhhhaaaarrrr ****hhhhoooosssstttt ==== """"llllooooccccaaaallllhhhhoooosssstttt"""";;;;
- CCCCOOOODDDDEEEE::::
- iiiiffff(((( iiiitttteeeemmmmssss >>>> 1111 ))))
- hhhhoooosssstttt ==== ((((cccchhhhaaaarrrr ****))))SSSSvvvvPPPPVVVV((((SSSSTTTT((((1111)))),,,, nnnnaaaa))));;;;
- RRRREEEETTTTVVVVAAAALLLL ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhhoooosssstttt,,,, &&&&ttttiiiimmmmeeeepppp ))));;;;
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
- RRRREEEETTTTVVVVAAAALLLL
-
-
- TTTThhhheeee AAAALLLLIIIIAAAASSSS:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- The ALIAS: keyword allows an XSUB to have two more more
- unique Perl names and to know which of those names was
- used when it was invoked. The Perl names may be fully-
- qualified with package names. Each alias is given an
- index. The compiler will setup a variable called iiiixxxx which
- contain the index of the alias which was used. When the
- XSUB is called with its declared name iiiixxxx will be 0.
-
- The following example will create aliases FFFFOOOOOOOO::::::::ggggeeeettttttttiiiimmmmeeee(((())))
- and BBBBAAAARRRR::::::::ggggeeeettttiiiitttt(((()))) for this function.
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- ttttiiiimmmmeeee____tttt &&&&ttttiiiimmmmeeeepppp
- AAAALLLLIIIIAAAASSSS::::
- FFFFOOOOOOOO::::::::ggggeeeettttttttiiiimmmmeeee ==== 1111
- BBBBAAAARRRR::::::::ggggeeeettttiiiitttt ==== 2222
- IIIINNNNIIIITTTT::::
- pppprrrriiiinnnnttttffff((((""""#### iiiixxxx ==== %%%%dddd\\\\nnnn"""",,,, iiiixxxx ))));;;;
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
-
-
-
-
-
-
- 15/Feb/96 perl 5.002 with 15
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- TTTThhhheeee IIIINNNNCCCCLLLLUUUUDDDDEEEE:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- This keyword can be used to pull other files into the XS
- module. The other files may have XS code. INCLUDE: can
- also be used to run a command to generate the XS code to
- be pulled into the module.
-
- The file _R_p_c_b_1_._x_s_h contains our rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((()))) function:
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- ttttiiiimmmmeeee____tttt &&&&ttttiiiimmmmeeeepppp
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
-
- The XS module can use INCLUDE: to pull that file into it.
-
- IIIINNNNCCCCLLLLUUUUDDDDEEEE:::: RRRRppppccccbbbb1111....xxxxsssshhhh
-
- If the parameters to the INCLUDE: keyword are followed by
- a pipe (||||) then the compiler will interpret the parameters
- as a command.
-
- IIIINNNNCCCCLLLLUUUUDDDDEEEE:::: ccccaaaatttt RRRRppppccccbbbb1111....xxxxsssshhhh ||||
-
-
- TTTThhhheeee CCCCAAAASSSSEEEE:::: KKKKeeeeyyyywwwwoooorrrrdddd
-
- The CASE: keyword allows an XSUB to have multiple distinct
- parts with each part acting as a virtual XSUB. CASE: is
- greedy and if it is used then all other XS keywords must
- be contained within a CASE:. This means nothing may
- precede the first CASE: in the XSUB and anything following
- the last CASE: is included in that case.
-
- A CASE: might switch via a parameter of the XSUB, via the
- iiiixxxx ALIAS: variable (see the section on _T_h_e _A_L_I_A_S_:
- _K_e_y_w_o_r_d), or maybe via the iiiitttteeeemmmmssss variable (see the section
- on _V_a_r_i_a_b_l_e_-_l_e_n_g_t_h _P_a_r_a_m_e_t_e_r _L_i_s_t_s). The last CASE:
- becomes the ddddeeeeffffaaaauuuulllltttt case if it is not associated with a
- conditional. The following example shows CASE switched
- via iiiixxxx with a function rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((()))) having an alias
- xxxx____ggggeeeettttttttiiiimmmmeeee(((()))). When the function is called as
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((()))) it's parameters are the usual ((((cccchhhhaaaarrrr ****hhhhoooosssstttt,,,,
- ttttiiiimmmmeeee____tttt ****ttttiiiimmmmeeeepppp)))), but when the function is called as
- xxxx____ggggeeeettttttttiiiimmmmeeee(((()))) is parameters are reversed, ((((ttttiiiimmmmeeee____tttt ****ttttiiiimmmmeeeepppp,,,,
- cccchhhhaaaarrrr ****hhhhoooosssstttt)))).
-
-
-
-
-
-
-
-
-
- 15/Feb/96 perl 5.002 with 16
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- lllloooonnnngggg
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((aaaa,,,,bbbb))))
- CCCCAAAASSSSEEEE:::: iiiixxxx ======== 1111
- AAAALLLLIIIIAAAASSSS::::
- xxxx____ggggeeeettttttttiiiimmmmeeee ==== 1111
- IIIINNNNPPPPUUUUTTTT::::
- #### ''''aaaa'''' iiiissss ttttiiiimmmmeeeepppp,,,, ''''bbbb'''' iiiissss hhhhoooosssstttt
- cccchhhhaaaarrrr ****bbbb
- ttttiiiimmmmeeee____tttt aaaa ==== NNNNOOOO____IIIINNNNIIIITTTT
- CCCCOOOODDDDEEEE::::
- RRRREEEETTTTVVVVAAAALLLL ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( bbbb,,,, &&&&aaaa ))));;;;
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- aaaa
- RRRREEEETTTTVVVVAAAALLLL
- CCCCAAAASSSSEEEE::::
- #### ''''aaaa'''' iiiissss hhhhoooosssstttt,,,, ''''bbbb'''' iiiissss ttttiiiimmmmeeeepppp
- cccchhhhaaaarrrr ****aaaa
- ttttiiiimmmmeeee____tttt &&&&bbbb ==== NNNNOOOO____IIIINNNNIIIITTTT
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- bbbb
- RRRREEEETTTTVVVVAAAALLLL
-
- That function can be called with either of the following
- statements. Note the different argument lists.
-
- $$$$ssssttttaaaattttuuuussss ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( $$$$hhhhoooosssstttt,,,, $$$$ttttiiiimmmmeeeepppp ))));;;;
-
- $$$$ssssttttaaaattttuuuussss ==== xxxx____ggggeeeettttttttiiiimmmmeeee(((( $$$$ttttiiiimmmmeeeepppp,,,, $$$$hhhhoooosssstttt ))));;;;
-
-
- TTTThhhheeee &&&& UUUUnnnnaaaarrrryyyy OOOOppppeeeerrrraaaattttoooorrrr
-
- The & unary operator is used to tell the compiler that it
- should dereference the object when it calls the C
- function. This is used when a CODE: block is not used and
- the object is a not a pointer type (the object is an iiiinnnntttt
- or lllloooonnnngggg but not a iiiinnnntttt**** or lllloooonnnngggg****).
-
- The following XSUB will generate incorrect C code. The
- xsubpp compiler will turn this into code which calls
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((()))) with parameters ((((cccchhhhaaaarrrr ****hhhhoooosssstttt,,,, ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp)))),
- but the real rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((()))) wants the ttttiiiimmmmeeeepppp parameter to
- be of type ttttiiiimmmmeeee____tttt**** rather than ttttiiiimmmmeeee____tttt.
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
-
- That problem is corrected by using the &&&& operator. The
- xsubpp compiler will now turn this into code which calls
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((()))) correctly with parameters ((((cccchhhhaaaarrrr ****hhhhoooosssstttt,,,,
-
-
-
- 15/Feb/96 perl 5.002 with 17
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- ttttiiiimmmmeeee____tttt ****ttttiiiimmmmeeeepppp)))). It does this by carrying the &&&& through,
- so the function call looks like rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,
- &&&&ttttiiiimmmmeeeepppp)))).
-
- bbbboooooooollll____tttt
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt,,,,ttttiiiimmmmeeeepppp))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- ttttiiiimmmmeeee____tttt &&&&ttttiiiimmmmeeeepppp
- OOOOUUUUTTTTPPPPUUUUTTTT::::
- ttttiiiimmmmeeeepppp
-
-
- IIIInnnnsssseeeerrrrttttiiiinnnngggg CCCCoooommmmmmmmeeeennnnttttssss aaaannnndddd CCCC PPPPrrrreeeepppprrrroooocccceeeessssssssoooorrrr DDDDiiiirrrreeeeccccttttiiiivvvveeeessss
-
- Comments and C preprocessor directives are allowed within
- CODE:, PPCODE:, BOOT:, and CLEANUP: blocks. The compiler
- will pass the preprocessor directives through untouched
- and will remove the commented lines. Comments can be
- added to XSUBs by placing a #### at the beginning of the
- line. Care should be taken to avoid making the comment
- look like a C preprocessor directive, lest it be
- interpreted as such.
-
- UUUUssssiiiinnnngggg XXXXSSSS WWWWiiiitttthhhh CCCC++++++++
-
- If a function is defined as a C++ method then it will
- assume its first argument is an object pointer. The
- object pointer will be stored in a variable called THIS.
- The object should have been created by C++ with the _n_e_w_(_)
- function and should be blessed by Perl with the
- _s_v___s_e_t_r_e_f___p_v_(_) macro. The blessing of the object by Perl
- can be handled by a typemap. An example typemap is shown
- at the end of this section.
-
- If the method is defined as static it will call the C++
- function using the _c_l_a_s_s_:_:_m_e_t_h_o_d_(_) syntax. If the method
- is not static the function will be called using the
- THIS->_m_e_t_h_o_d_(_) syntax.
-
- The next examples will use the following C++ class.
-
- ccccllllaaaassssssss ccccoooolllloooorrrr {{{{
- ppppuuuubbbblllliiiicccc::::
- ccccoooolllloooorrrr(((())));;;;
- ~~~~ccccoooolllloooorrrr(((())));;;;
- iiiinnnntttt bbbblllluuuueeee(((())));;;;
- vvvvooooiiiidddd sssseeeetttt____bbbblllluuuueeee(((( iiiinnnntttt ))));;;;
-
- pppprrrriiiivvvvaaaatttteeee::::
- iiiinnnntttt cccc____bbbblllluuuueeee;;;;
- }}}};;;;
-
- The XSUBs for the _b_l_u_e_(_) and _s_e_t___b_l_u_e_(_) methods are
- defined with the class name but the parameter for the
-
-
-
- 15/Feb/96 perl 5.002 with 18
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- object (THIS, or "self") is implicit and is not listed.
-
- iiiinnnntttt
- ccccoooolllloooorrrr::::::::bbbblllluuuueeee(((())))
-
- vvvvooooiiiidddd
- ccccoooolllloooorrrr::::::::sssseeeetttt____bbbblllluuuueeee(((( vvvvaaaallll ))))
- iiiinnnntttt vvvvaaaallll
-
- Both functions will expect an object as the first
- parameter. The xsubpp compiler will call that object TTTTHHHHIIIISSSS
- and will use it to call the specified method. So in the
- C++ code the _b_l_u_e_(_) and _s_e_t___b_l_u_e_(_) methods will be called
- in the following manner.
-
- RRRREEEETTTTVVVVAAAALLLL ==== TTTTHHHHIIIISSSS---->>>>bbbblllluuuueeee(((())));;;;
-
- TTTTHHHHIIIISSSS---->>>>sssseeeetttt____bbbblllluuuueeee(((( vvvvaaaallll ))));;;;
-
- If the function's name is DDDDEEEESSSSTTTTRRRROOOOYYYY then the C++ ddddeeeelllleeeetttteeee
- function will be called and TTTTHHHHIIIISSSS will be given as its
- parameter.
-
- vvvvooooiiiidddd
- ccccoooolllloooorrrr::::::::DDDDEEEESSSSTTTTRRRROOOOYYYY(((())))
-
- The C++ code will call ddddeeeelllleeeetttteeee.
-
- ddddeeeelllleeeetttteeee TTTTHHHHIIIISSSS;;;;
-
- If the function's name is nnnneeeewwww then the C++ nnnneeeewwww function
- will be called to create a dynamic C++ object. The XSUB
- will expect the class name, which will be kept in a
- variable called CCCCLLLLAAAASSSSSSSS, to be given as the first argument.
-
- ccccoooolllloooorrrr ****
- ccccoooolllloooorrrr::::::::nnnneeeewwww(((())))
-
- The C++ code will call nnnneeeewwww.
-
- RRRREEEETTTTVVVVAAAALLLL ==== nnnneeeewwww ccccoooolllloooorrrr(((())));;;;
-
- The following is an example of a typemap that could be
- used for this C++ example.
-
- TTTTYYYYPPPPEEEEMMMMAAAAPPPP
- ccccoooolllloooorrrr **** OOOO____OOOOBBBBJJJJEEEECCCCTTTT
-
-
-
-
-
-
-
-
-
-
- 15/Feb/96 perl 5.002 with 19
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- OOOOUUUUTTTTPPPPUUUUTTTT
- #### TTTThhhheeee PPPPeeeerrrrllll oooobbbbjjjjeeeecccctttt iiiissss bbbblllleeeesssssssseeeedddd iiiinnnnttttoooo ''''CCCCLLLLAAAASSSSSSSS'''',,,, wwwwhhhhiiiicccchhhh sssshhhhoooouuuulllldddd bbbbeeee aaaa
- #### cccchhhhaaaarrrr**** hhhhaaaavvvviiiinnnngggg tttthhhheeee nnnnaaaammmmeeee ooooffff tttthhhheeee ppppaaaacccckkkkaaaaggggeeee ffffoooorrrr tttthhhheeee bbbblllleeeessssssssiiiinnnngggg....
- OOOO____OOOOBBBBJJJJEEEECCCCTTTT
- ssssvvvv____sssseeeettttrrrreeeeffff____ppppvvvv(((( $$$$aaaarrrrgggg,,,, CCCCLLLLAAAASSSSSSSS,,,, ((((vvvvooooiiiidddd****))))$$$$vvvvaaaarrrr ))));;;;
-
- IIIINNNNPPPPUUUUTTTT
- OOOO____OOOOBBBBJJJJEEEECCCCTTTT
- iiiiffff(((( ssssvvvv____iiiissssoooobbbbjjjjeeeecccctttt(((($$$$aaaarrrrgggg)))) &&&&&&&& ((((SSSSvvvvTTTTYYYYPPPPEEEE((((SSSSvvvvRRRRVVVV(((($$$$aaaarrrrgggg)))))))) ======== SSSSVVVVtttt____PPPPVVVVMMMMGGGG)))) ))))
- $$$$vvvvaaaarrrr ==== (((($$$$ttttyyyyppppeeee))))SSSSvvvvIIIIVVVV((((((((SSSSVVVV****))))SSSSvvvvRRRRVVVV(((( $$$$aaaarrrrgggg ))))))));;;;
- eeeellllsssseeee{{{{
- wwwwaaaarrrrnnnn(((( \\\\""""$$$${{{{PPPPaaaacccckkkkaaaaggggeeee}}}}::::::::$$$$ffffuuuunnnncccc____nnnnaaaammmmeeee(((()))) -------- $$$$vvvvaaaarrrr iiiissss nnnnooootttt aaaa bbbblllleeeesssssssseeeedddd SSSSVVVV rrrreeeeffffeeeerrrreeeennnncccceeee\\\\"""" ))));;;;
- XXXXSSSSRRRREEEETTTTUUUURRRRNNNN____UUUUNNNNDDDDEEEEFFFF;;;;
- }}}}
-
-
- IIIInnnntttteeeerrrrffffaaaacccceeee SSSSttttrrrraaaatttteeeeggggyyyy
-
- When designing an interface between Perl and a C library a
- straight translation from C to XS is often sufficient.
- The interface will often be very C-like and occasionally
- nonintuitive, especially when the C function modifies one
- of its parameters. In cases where the programmer wishes
- to create a more Perl-like interface the following
- strategy may help to identify the more critical parts of
- the interface.
-
- Identify the C functions which modify their parameters.
- The XSUBs for these functions may be able to return lists
- to Perl, or may be candidates to return undef or an empty
- list in case of failure.
-
- Identify which values are used by only the C and XSUB
- functions themselves. If Perl does not need to access the
- contents of the value then it may not be necessary to
- provide a translation for that value from C to Perl.
-
- Identify the pointers in the C function parameter lists
- and return values. Some pointers can be handled in XS
- with the & unary operator on the variable name while
- others will require the use of the * operator on the type
- name. In general it is easier to work with the &
- operator.
-
- Identify the structures used by the C functions. In many
- cases it may be helpful to use the T_PTROBJ typemap for
- these structures so they can be manipulated by Perl as
- blessed objects.
-
- PPPPeeeerrrrllll OOOObbbbjjjjeeeeccccttttssss AAAAnnnndddd CCCC SSSSttttrrrruuuuccccttttuuuurrrreeeessss
-
- When dealing with C structures one should select either
- TTTT____PPPPTTTTRRRROOOOBBBBJJJJ or TTTT____PPPPTTTTRRRRRRRREEEEFFFF for the XS type. Both types are
- designed to handle pointers to complex objects. The
-
-
-
- 15/Feb/96 perl 5.002 with 20
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- T_PTRREF type will allow the Perl object to be unblessed
- while the T_PTROBJ type requires that the object be
- blessed. By using T_PTROBJ one can achieve a form of
- type-checking because the XSUB will attempt to verify that
- the Perl object is of the expected type.
-
- The following XS code shows the _g_e_t_n_e_t_c_o_n_f_i_g_e_n_t_(_) function
- which is used with ONC+ TIRPC. The _g_e_t_n_e_t_c_o_n_f_i_g_e_n_t_(_)
- function will return a pointer to a C structure and has
- the C prototype shown below. The example will demonstrate
- how the C pointer will become a Perl reference. Perl will
- consider this reference to be a pointer to a blessed
- object and will attempt to call a destructor for the
- object. A destructor will be provided in the XS source to
- free the memory used by _g_e_t_n_e_t_c_o_n_f_i_g_e_n_t_(_). Destructors in
- XS can be created by specifying an XSUB function whose
- name ends with the word DDDDEEEESSSSTTTTRRRROOOOYYYY. XS destructors can be
- used to free memory which may have been malloc'd by
- another XSUB.
-
- ssssttttrrrruuuucccctttt nnnneeeettttccccoooonnnnffffiiiigggg ****ggggeeeettttnnnneeeettttccccoooonnnnffffiiiiggggeeeennnntttt((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****nnnneeeettttiiiidddd))));;;;
-
- A ttttyyyyppppeeeeddddeeeeffff will be created for ssssttttrrrruuuucccctttt nnnneeeettttccccoooonnnnffffiiiigggg. The Perl
- object will be blessed in a class matching the name of the
- C type, with the tag PPPPttttrrrr appended, and the name should not
- have embedded spaces if it will be a Perl package name.
- The destructor will be placed in a class corresponding to
- the class of the object and the PREFIX keyword will be
- used to trim the name to the word DESTROY as Perl will
- expect.
-
- ttttyyyyppppeeeeddddeeeeffff ssssttttrrrruuuucccctttt nnnneeeettttccccoooonnnnffffiiiigggg NNNNeeeettttccccoooonnnnffffiiiigggg;;;;
-
- MMMMOOOODDDDUUUULLLLEEEE ==== RRRRPPPPCCCC PPPPAAAACCCCKKKKAAAAGGGGEEEE ==== RRRRPPPPCCCC
-
- NNNNeeeettttccccoooonnnnffffiiiigggg ****
- ggggeeeettttnnnneeeettttccccoooonnnnffffiiiiggggeeeennnntttt((((nnnneeeettttiiiidddd))))
- cccchhhhaaaarrrr ****nnnneeeettttiiiidddd
-
- MMMMOOOODDDDUUUULLLLEEEE ==== RRRRPPPPCCCC PPPPAAAACCCCKKKKAAAAGGGGEEEE ==== NNNNeeeettttccccoooonnnnffffiiiiggggPPPPttttrrrr PPPPRRRREEEEFFFFIIIIXXXX ==== rrrrppppccccbbbb____
-
- vvvvooooiiiidddd
- rrrrppppccccbbbb____DDDDEEEESSSSTTTTRRRROOOOYYYY((((nnnneeeettttccccoooonnnnffff))))
- NNNNeeeettttccccoooonnnnffffiiiigggg ****nnnneeeettttccccoooonnnnffff
- CCCCOOOODDDDEEEE::::
- pppprrrriiiinnnnttttffff((((""""NNNNoooowwww iiiinnnn NNNNeeeettttccccoooonnnnffffiiiiggggPPPPttttrrrr::::::::DDDDEEEESSSSTTTTRRRROOOOYYYY\\\\nnnn""""))));;;;
- ffffrrrreeeeeeee(((( nnnneeeettttccccoooonnnnffff ))));;;;
-
- This example requires the following typemap entry.
- Consult the typemap section for more information about
- adding new typemaps for an extension.
-
- TTTTYYYYPPPPEEEEMMMMAAAAPPPP
- NNNNeeeettttccccoooonnnnffffiiiigggg **** TTTT____PPPPTTTTRRRROOOOBBBBJJJJ
-
-
-
- 15/Feb/96 perl 5.002 with 21
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- This example will be used with the following Perl
- statements.
-
- uuuusssseeee RRRRPPPPCCCC;;;;
- $$$$nnnneeeettttccccoooonnnnffff ==== ggggeeeettttnnnneeeettttccccoooonnnnffffiiiiggggeeeennnntttt((((""""uuuuddddpppp""""))));;;;
-
- When Perl destroys the object referenced by $$$$nnnneeeettttccccoooonnnnffff it
- will send the object to the supplied XSUB DESTROY
- function. Perl cannot determine, and does not care, that
- this object is a C struct and not a Perl object. In this
- sense, there is no difference between the object created
- by the _g_e_t_n_e_t_c_o_n_f_i_g_e_n_t_(_) XSUB and an object created by a
- normal Perl subroutine.
-
- TTTThhhheeee TTTTyyyyppppeeeemmmmaaaapppp
-
- The typemap is a collection of code fragments which are
- used by the xxxxssssuuuubbbbpppppppp compiler to map C function parameters
- and values to Perl values. The typemap file may consist
- of three sections labeled TTTTYYYYPPPPEEEEMMMMAAAAPPPP, IIIINNNNPPPPUUUUTTTT, and OOOOUUUUTTTTPPPPUUUUTTTT. The
- INPUT section tells the compiler how to translate Perl
- values into variables of certain C types. The OUTPUT
- section tells the compiler how to translate the values
- from certain C types into values Perl can understand. The
- TYPEMAP section tells the compiler which of the INPUT and
- OUTPUT code fragments should be used to map a given C type
- to a Perl value. Each of the sections of the typemap must
- be preceded by one of the TYPEMAP, INPUT, or OUTPUT
- keywords.
-
- The default typemap in the eeeexxxxtttt directory of the Perl
- source contains many useful types which can be used by
- Perl extensions. Some extensions define additional
- typemaps which they keep in their own directory. These
- additional typemaps may reference INPUT and OUTPUT maps in
- the main typemap. The xxxxssssuuuubbbbpppppppp compiler will allow the
- extension's own typemap to override any mappings which are
- in the default typemap.
-
- Most extensions which require a custom typemap will need
- only the TYPEMAP section of the typemap file. The custom
- typemap used in the _g_e_t_n_e_t_c_o_n_f_i_g_e_n_t_(_) example shown
- earlier demonstrates what may be the typical use of
- extension typemaps. That typemap is used to equate a C
- structure with the T_PTROBJ typemap. The typemap used by
- _g_e_t_n_e_t_c_o_n_f_i_g_e_n_t_(_) is shown here. Note that the C type is
- separated from the XS type with a tab and that the C unary
- operator **** is considered to be a part of the C type name.
-
- TTTTYYYYPPPPEEEEMMMMAAAAPPPP
- NNNNeeeettttccccoooonnnnffffiiiigggg ****<<<<ttttaaaabbbb>>>>TTTT____PPPPTTTTRRRROOOOBBBBJJJJ
-
-
-
-
-
-
- 15/Feb/96 perl 5.002 with 22
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
- File RRRRPPPPCCCC....xxxxssss: Interface to some ONC+ RPC bind library
- functions.
-
- ####iiiinnnncccclllluuuuddddeeee """"EEEEXXXXTTTTEEEERRRRNNNN....hhhh""""
- ####iiiinnnncccclllluuuuddddeeee """"ppppeeeerrrrllll....hhhh""""
- ####iiiinnnncccclllluuuuddddeeee """"XXXXSSSSUUUUBBBB....hhhh""""
-
- ####iiiinnnncccclllluuuuddddeeee <<<<rrrrppppcccc////rrrrppppcccc....hhhh>>>>
-
- ttttyyyyppppeeeeddddeeeeffff ssssttttrrrruuuucccctttt nnnneeeettttccccoooonnnnffffiiiigggg NNNNeeeettttccccoooonnnnffffiiiigggg;;;;
-
- MMMMOOOODDDDUUUULLLLEEEE ==== RRRRPPPPCCCC PPPPAAAACCCCKKKKAAAAGGGGEEEE ==== RRRRPPPPCCCC
-
- vvvvooooiiiidddd
- rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((hhhhoooosssstttt====""""llllooooccccaaaallllhhhhoooosssstttt""""))))
- cccchhhhaaaarrrr ****hhhhoooosssstttt
- PPPPRRRREEEEIIIINNNNIIIITTTT::::
- ttttiiiimmmmeeee____tttt ttttiiiimmmmeeeepppp;;;;
- CCCCOOOODDDDEEEE::::
- SSSSTTTT((((0000)))) ==== ssssvvvv____nnnneeeewwwwmmmmoooorrrrttttaaaallll(((())));;;;
- iiiiffff(((( rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((( hhhhoooosssstttt,,,, &&&&ttttiiiimmmmeeeepppp )))) ))))
- ssssvvvv____sssseeeettttnnnnvvvv(((( SSSSTTTT((((0000)))),,,, ((((ddddoooouuuubbbblllleeee))))ttttiiiimmmmeeeepppp ))));;;;
-
- NNNNeeeettttccccoooonnnnffffiiiigggg ****
- ggggeeeettttnnnneeeettttccccoooonnnnffffiiiiggggeeeennnntttt((((nnnneeeettttiiiidddd====""""uuuuddddpppp""""))))
- cccchhhhaaaarrrr ****nnnneeeettttiiiidddd
-
- MMMMOOOODDDDUUUULLLLEEEE ==== RRRRPPPPCCCC PPPPAAAACCCCKKKKAAAAGGGGEEEE ==== NNNNeeeettttccccoooonnnnffffiiiiggggPPPPttttrrrr PPPPRRRREEEEFFFFIIIIXXXX ==== rrrrppppccccbbbb____
-
- vvvvooooiiiidddd
- rrrrppppccccbbbb____DDDDEEEESSSSTTTTRRRROOOOYYYY((((nnnneeeettttccccoooonnnnffff))))
- NNNNeeeettttccccoooonnnnffffiiiigggg ****nnnneeeettttccccoooonnnnffff
- CCCCOOOODDDDEEEE::::
- pppprrrriiiinnnnttttffff((((""""NNNNeeeettttccccoooonnnnffffiiiiggggPPPPttttrrrr::::::::DDDDEEEESSSSTTTTRRRROOOOYYYY\\\\nnnn""""))));;;;
- ffffrrrreeeeeeee(((( nnnneeeettttccccoooonnnnffff ))));;;;
-
- File ttttyyyyppppeeeemmmmaaaapppp: Custom typemap for RPC.xs.
-
- TTTTYYYYPPPPEEEEMMMMAAAAPPPP
- NNNNeeeettttccccoooonnnnffffiiiigggg **** TTTT____PPPPTTTTRRRROOOOBBBBJJJJ
-
- File RRRRPPPPCCCC....ppppmmmm: Perl module for the RPC extension.
-
- ppppaaaacccckkkkaaaaggggeeee RRRRPPPPCCCC;;;;
-
- rrrreeeeqqqquuuuiiiirrrreeee EEEExxxxppppoooorrrrtttteeeerrrr;;;;
- rrrreeeeqqqquuuuiiiirrrreeee DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr;;;;
- @@@@IIIISSSSAAAA ==== qqqqwwww((((EEEExxxxppppoooorrrrtttteeeerrrr DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr))));;;;
- @@@@EEEEXXXXPPPPOOOORRRRTTTT ==== qqqqwwww((((rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee ggggeeeettttnnnneeeettttccccoooonnnnffffiiiiggggeeeennnntttt))));;;;
-
- bbbboooooooottttssssttttrrrraaaapppp RRRRPPPPCCCC;;;;
- 1111;;;;
-
-
-
-
- 15/Feb/96 perl 5.002 with 23
-
-
-
-
-
- PERLXS(1) User Contributed Perl Documentation PERLXS(1)
-
-
- File rrrrppppcccctttteeeesssstttt....ppppllll: Perl test program for the RPC extension.
-
- uuuusssseeee RRRRPPPPCCCC;;;;
-
- $$$$nnnneeeettttccccoooonnnnffff ==== ggggeeeettttnnnneeeettttccccoooonnnnffffiiiiggggeeeennnntttt(((())));;;;
- $$$$aaaa ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee(((())));;;;
- pppprrrriiiinnnntttt """"ttttiiiimmmmeeee ==== $$$$aaaa\\\\nnnn"""";;;;
- pppprrrriiiinnnntttt """"nnnneeeettttccccoooonnnnffff ==== $$$$nnnneeeettttccccoooonnnnffff\\\\nnnn"""";;;;
-
- $$$$nnnneeeettttccccoooonnnnffff ==== ggggeeeettttnnnneeeettttccccoooonnnnffffiiiiggggeeeennnntttt((((""""ttttccccpppp""""))));;;;
- $$$$aaaa ==== rrrrppppccccbbbb____ggggeeeettttttttiiiimmmmeeee((((""""ppppooooppppllllaaaarrrr""""))));;;;
- pppprrrriiiinnnntttt """"ttttiiiimmmmeeee ==== $$$$aaaa\\\\nnnn"""";;;;
- pppprrrriiiinnnntttt """"nnnneeeettttccccoooonnnnffff ==== $$$$nnnneeeettttccccoooonnnnffff\\\\nnnn"""";;;;
-
-
- XXXXSSSS VVVVEEEERRRRSSSSIIIIOOOONNNN
- This document covers features supported by xxxxssssuuuubbbbpppppppp 1.933.
-
- AAAAUUUUTTTTHHHHOOOORRRR
- Dean Roehrich _<_r_o_e_h_r_i_c_h_@_c_r_a_y_._c_o_m_> Feb 13, 1996
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- 15/Feb/96 perl 5.002 with 24
-
-
-